Toolboxes

If your application allows users to create or modify diagrams, you will need to provide some kind of user interface for creating new nodes and connections. WPF Diagrams provides a standard toolbox control, or you can create your user interface or leverage the classes and resources provided.

The easiest way to provide a user interface for adding elements to diagrams is to use the DiagramToolBox control. A DiagramToolBox contains a number of tools, each either a DiagramNodeTool for creating nodes, or a DiagramConnectionTool for connecting nodes (that is, creating connections).

Toolbox Items for Creating Nodes

For a tool to create simple shape nodes, specify a DiagramNodeTool with the ShapeTool.Shape attached property:

CopyA toolbox item for creating rectangle nodes

<ms:DiagramNodeTool ms:ShapeTool.Shape="Rectangle" />

You can also create tools for user-defined shapes in the same way:

CopyA toolbox item for creating nodes of a custom shape

<ms:DiagramNodeTool ms:ShapeTool.Shape="{x:Static local:MyShapes.WShape}" />

Toolbox items for nodes have the following behaviour:

The user can drag an item and drop it onto the DiagramSurface to create a node of default size at the drop location.
The user can click on an item, move the cursor over the DiagramSurface, and click again to create a node of default size at the second click location. (This is referred to as a “charged cursor” because the first click “charges up” the mouse pointer with the appropriate node type.)
The user can click on an item, move the cursor over the DiagramSurface, and drag the cursor across the DiagramSurface to create a node sized to fit the drag rectangle.

Toolbox Items for Connecting Nodes

For a tool to connect nodes using simple lines, specify a DiagramConnectionTool with the ConnectionTool.LineType attached property. As with nodes, this can be a built-in line type or a user-defined line type:

CopyToolbox items for creating connections

<ms:DiagramConnectionTool ms:ConnectionTool.LineType="ElbowDoubleArrow" />
<ms:DiagramConnectionTool ms:ConnectionTool.LineType="{x:Static local:MyShapes.DashedPinkLineWithArrow}" />

The user interface for toolbox connection items is to click on the item and then drag from one connection point to another. The selection remains in effect after drawing a line, making it easy for the user to draw multiple connections of the same kind.

Using the DiagramToolBox Control

A DiagramToolbox is divided into a number of groups, represented by DiagramToolBoxGroup entries. The toolbox control allows the user to show and hide groups to avoid clutter. Each group contains a number of tools as described above.

CopyUsing the DiagramToolBox control

<ms:DiagramToolBox>
  <ms:DiagramToolBoxGroup Header="Lines">
    <ms:DiagramConnectionTool ms:ConnectionTool.LineType="Straight" />
    <ms:DiagramConnectionTool ms:ConnectionTool.LineType="StraightArrow" />
    <ms:DiagramConnectionTool ms:ConnectionTool.LineType="StraightDoubleArrow" />
  </ms:DiagramToolBoxGroup>
  <ms:DiagramToolBoxGroup Header="Shapes">
    <ms:DiagramNodeTool ms:ShapeTool.Shape="Rectangle" />
    <ms:DiagramNodeTool ms:ShapeTool.Shape="Ellipse" />
    <ms:DiagramNodeTool ms:ShapeTool.Shape="{x:Static local:MyShapes.Triskaidecagon}" />
  </ms:DiagramToolBoxGroup>
  <ms:DiagramToolBoxGroup Header="Annotations">
    <StaticResource ResourceKey="{x:Static ms:DiagramShapes.TitleNodeToolKey}" />
    <StaticResource ResourceKey="{x:Static ms:DiagramShapes.CommentNodeToolKey}" />
  </ms:DiagramToolBoxGroup>
</ms:DiagramToolBox>

Standard Toolbox Items

WPF Diagrams contains a number of assemblies for working with specific diagram types such as flow diagrams. These assemblies contain standard toolbox items which you can use in a DiagramToolBox. To do this, merge the relevant resource dictionary into your resources section, then reference the toolbox items you want to use with a StaticResource element.

CopyUsing flow diagram toolbox items

<Window.Resources>
  <ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
      <ms:StandardFlowDiagramToolBoxItems />
    </ResourceDictionary.MergedDictionaries>
  </ResourceDictionary>
</Window.Resources>

<ms:DiagramToolBox>
  <ms:DiagramToolBoxGroup Header="Flowchart">
    <StaticResource ResourceKey="{x:Static ms:StandardFlowDiagramToolBoxItems.StartNodeToolKey}" />
    <StaticResource ResourceKey="{x:Static ms:StandardFlowDiagramToolBoxItems.DecisionNodeToolKey}" />
    <StaticResource ResourceKey="{x:Static ms:StandardFlowDiagramToolBoxItems.EndNodeToolKey}" />
    <StaticResource ResourceKey="{x:Static ms:DiagramShapes.TitleNodeToolKey}" />
    <StaticResource ResourceKey="{x:Static ms:DiagramShapes.CommentNodeToolKey}" />
  </ms:DiagramToolBoxGroup>
</ms:DiagramToolBox>

Notice that you must merge in the relevant resource dictionary to be able to access these resources.

Customising the Appearance of Toolbox Icons

To customise the appearance of shapes and lines in the toolbox, apply the ShapeTool.ShapePathStyle, ConnectionTool.ConnectionPathStyle and ConnectionTool.ArrowPathStyle attached properties. (Note that these properties affect only tools set up through the ShapeTool and ConnectionTool attached properties. The WPF Diagrams Foundation supports hand-crafting of toolbox items and these are not affected by the auto tool properties.) In each case the value should be a style whose target type is Path.

The attached properties can be applied at the DiagramToolBox level, to style all toolbox items, or at the individual item level.

CopyCustomising the appearance of toolbox icons

<Window.Resources>
  <Style x:Key="ToolboxNodePathStyle" TargetType="Path">
    <Setter Property="Stroke" Value="Red" />
    <Setter Property="StrokeThickness" Value="1" />
    <Setter Property="Fill" Value="Pink" />
    <Setter Property="Stretch" Value="Fill" />
  </Style>

  <Style x:Key="ToolboxLinePathStyle" TargetType="Path">
    <Setter Property="Stroke" Value="Yellow" />
    <Setter Property="StrokeThickness" Value="3" />
    <Setter Property="Stretch" Value="Fill" />
    <Setter Property="Width" Value="40" />
    <Setter Property="Height" Value="30" />
  </Style>

  <Style x:Key="ToolboxArrowPathStyle" TargetType="Path">
    <Setter Property="Fill" Value="Lime" />
    <Setter Property="StrokeThickness" Value="0" />
  </Style>
</Window.Resources>

<ms:DiagramToolBox ms:ShapeTool.ShapePathStyle="{StaticResource ToolboxNodePathStyle}" 
                   ms:ConnectionTool.ConnectionPathStyle="{StaticResource ToolboxLinePathStyle}" 
                   ms:ConnectionTool.ArrowPathStyle="{StaticResource ToolboxArrowPathStyle}" 
                   >
  <ms:DiagramToolBoxGroup Header="Lines">
    <!-- Gets the toolbox-level style -->
    <ms:DiagramConnectionTool ms:ConnectionTool.LineType="Elbow" />
    <!-- Overrides the toolbox-level style -->
    <ms:DiagramConnectionTool ms:ConnectionTool.LineType="ElbowArrow">
      <ms:ConnectionTool.ConnectionPathStyle>
        <Style TargetType="Path" BasedOn="{StaticResource ToolboxLinePathStyle}">
          <Setter Property="Stroke" Value="Red" />
        </Style>
      </ms:ConnectionTool.ConnectionPathStyle>
    </ms:DiagramConnectionTool>
  </ms:DiagramToolBoxGroup>
  <ms:DiagramToolBoxGroup Header="Basic Shapes">
    <!-- Gets the toolbox-level style -->
    <ms:DiagramNodeTool ms:ShapeTool.Shape="Rectangle" />
    <!-- Overrides the toolbox-level style -->
    <ms:DiagramNodeTool ms:ShapeTool.Shape="Ellipse">
      <ms:ShapeTool.ShapePathStyle>
        <Style TargetType="Path" BasedOn="{StaticResource ToolboxNodePathStyle}">
          <Setter Property="Fill" Value="Lime" />
        </Style>
      </ms:ShapeTool.ShapePathStyle>
    </ms:DiagramNodeTool>
  </ms:DiagramToolBoxGroup>
</ms:DiagramToolBox>